home *** CD-ROM | disk | FTP | other *** search
/ By Popular Request 2.0 / By Popular Request 2.0 (Arsenal Computer).ISO / amiga_6 / vrctr116.lha / VerCtrl.doc < prev    next >
Text File  |  1995-08-05  |  9KB  |  227 lines
  1. /*----------------------------------------------------------------------*/
  2.                             VerCtrl.rexx v1.16
  3.  
  4.                 An AREXX development environment for Opus5
  5.  
  6.               by Dave Freeman (dfreeman@icecave.apana.org.au)
  7.  
  8. /*----------------------------------------------------------------------*/
  9.  
  10.  
  11. Description:
  12. ~~~~~~~~~~~~
  13.  
  14. The contents of this archive form the basis of my own AREXX development
  15. environment.  It provides a method for creating new projects and for
  16. managing projects under way such that version information is maintained in
  17. an AmigaDOS compliant way (i.e. the AmigaDOS 'Version' command works on my
  18. AREXX scripts).
  19.  
  20. This system also provides an easy way for me to start a new project with a
  21. script that already contains the basic layout that I normally use including
  22. such things are error trapping, readargs() style argument handling and
  23. other procedures and concepts that I like to use.
  24.  
  25.  
  26. Requirments:
  27. ~~~~~~~~~~~~
  28.  
  29. To fully install and use the contents of this archive you will need the
  30. following:
  31.  
  32.          AREXX - part of AmigaDOS since release 2
  33.          DirectoryOpus v5 - I use v5.11
  34.          CygnusEd Text Editor - I use v3.5
  35.          rexxdossupport.library v2.3 by hartmut Goebel
  36.  
  37.  
  38. I have included RexxDosSupport.lha in the 'Extras' directory of this
  39. archive but it can also be found on AmiNet in util/rexx if you are looking
  40. for a different version or whatever.
  41.  
  42. While I list these as requirements it would not be difficult to modify the
  43. contents of this archive to suit just about any environment with the
  44. exception of the need to have AREXX to write AREXX scripts.  :)
  45.  
  46.  
  47. Installation:
  48. ~~~~~~~~~~~~~
  49.  
  50. I will describe my own setup here.  It should make it fairly obvious what
  51. you will need to change to suit your own particular needs on your own
  52. machine.
  53.  
  54. 1.  Create a directory to store your AREXX projects.  Sub-directories will
  55. be created as required.  i.e.  Work:RexxDev
  56.  
  57. 2.  Move VerCtrl.rexx to the directory you have just created (or anywhere
  58. else that you want to call it from really, it doesn't really need to be
  59. anywhere in particular).
  60.  
  61. 3.  Move RexxProg.rexx to your REXX: directory.
  62.  
  63. 4.  Copy the included RexxDosSupport.library to LIBS:
  64.  
  65. 5.  Copy Images/EdRexx.small to DOpus5:Images (I know, it's not much of an
  66. image - perhaps some artist out there can improve it <g>).
  67.  
  68. 6.  Edit your Lister ToolBar (Menu -> Lister -> Edit Lister Toolbar...) and
  69. add a new button (Add gadget).
  70.  
  71. 7.  Edit the new button you just created.  Add the EdRexx.small button as
  72. the image.
  73.  
  74. 8.  On the LMB I use the following:
  75.  
  76.     Function:
  77.     ARexx          Work:RexxDev/VerCtrl.rexx (ou) {s}
  78.     AmigaDOS       Work:CygnusEd/Ed {f}
  79.  
  80.     Flags:         CD source
  81.                    No file quote
  82.  
  83. 9.  On the RMB I use the following:
  84.  
  85.     Function:
  86.     ARexx          Work:RexxDev/VerCtrl.rexx {RsEnter New AREXX Project
  87.                                                name...:Test.rexx} {s} New
  88.     AmigaDOS       Work:CygnusEd/Ed `GetENV RexxDev.File`
  89.     AmigaDOS       UnSetENV RexxDev.File
  90.  
  91.     Flags:         CD source
  92.                    No file quote
  93.                    Rescan source
  94.  
  95. 10. That's pretty much it for my standard installation.
  96.  
  97.  
  98. What it does:
  99. ~~~~~~~~~~~~~
  100.  
  101. VerCtrl.rexx is the main control script.  It takes three arguments.  The
  102. first argument is the name of the file to edit (it does not _have_ to end
  103. in '.rexx' but '.rexx' will be added to it if there is no other extension -
  104. an extension, in this case, is defined as any filename that has at least
  105. one period '.' in it).  The second argument is the path contains the file
  106. you wish to edit.  This path should exist, obviously, since you are going
  107. to edit a file in that path.  If you are creating a new project then you
  108. use the 'New' switch.  The third argument is a switch that lets you tell
  109. VerCtrl.rexx to create a new directory for this project - the switch is
  110. optional.
  111.  
  112. When VerCtrl.rexx is invoked it will look for the given file in the given
  113. directory.  If the file is not found then the script will fail.  If you are
  114. using this script from Opus5 then you will normally be running this script
  115. from a button so failure is not likely in this case.  If the 'New' switch
  116. is also given then a new project will be created.  This new project will be
  117. created in a new directory.  The new directory will be created as a
  118. sub-directory of the current directory.
  119.  
  120. It is the creation of this new AREXX script that REXX:RexxProg.rexx is used
  121. for.  This is the script that forms the basis for most of the AREXX scripts
  122. that I write.  It contains elements that I like to have in all of my AREXX
  123. scripts.  If you always want to include other items in your AREXX script
  124. then add them to this file.  You can change anything you like in the script
  125. as long as you retain certain elements.  Basically, VerCtrl.rexx writes a
  126. new version string in two places every time it is used.  I use a standard
  127. format for the first few lines of my AREXX programs as follows:
  128.  
  129.   -----8<-----
  130. 1-  /*\
  131. 2-   *
  132. 3-   *  $VER: 
  133. 4-   *
  134. 5-  \*/
  135. 6- 
  136. 7-  VersMsg = 
  137. 8-  Author  = "Dave Freeman"
  138. 9-  Contact = "dfreeman@icecave.apana.org.au"
  139.   -----8<-----
  140.  
  141. Line 3 and line 7 are altered by VerCtrl.rexx each time it is executed.
  142. These two lines are identified by a search for ' *  $VER:' and 'VersMsg = '
  143. respectively.  You should avoid having any other matches for these two
  144. strings in your own scripts.  It does not matter where in the script these
  145. two lines end up being, they will be found and altered.
  146.  
  147. I like to be able to easily output an information message in some programs
  148. and the two variables Author and Contact are set for my use.  You should
  149. alter them accordingly to suit your own particular needs.
  150.  
  151. In general I would suggest that you make any changes to the comment block
  152. at the start of the program at a point after line 3 and leave line 1 and
  153. line 5 in their current format (just copy line 4 and add comments on a line
  154. similair to that one as required).
  155.  
  156. When used from Opus5 the final result will be that you can click on an
  157. AREXX script and use VerCtrl.rexx to search out the AmigaDOS version string
  158. and increment the revision number and set the date to today's date
  159. (assuming your system clock is correct).  It will then load that file into
  160. your text editor ready for you to continue development.
  161.  
  162. If you want to create a new AREXX project just click on the toolbar button
  163. with the right mouse and it will prompt for a new project name to create.
  164. VerCtrl.rexx will then create the new directory and place a new AREXX
  165. script of the required name in that directory.  The new script will have a
  166. valid AmigaDOS version string and will contain whatever you have in the
  167. 'shell' AREXX script 'REXX:RexxProg.rexx'.
  168.  
  169. A new feature with v1.15 is the ability to use multiple 'shell' AREXX
  170. scripts.  This enables you to, for example, have a 'shell' AREXX script for
  171. developing scripts for DOpus5 and another one for use in AmigaDOS shells
  172. and another for use with a BBS program and so on.  Each 'shell' script is
  173. identified by it's extension in much the same way that CygnusEd identifies
  174. the appropriate environment to load.  In this case, VerCtrl.rexx will first
  175. look for REXX:RexxProg.extension where extension will match whatever
  176. follows the LAST period '.' in the given filename (.dopus5 or .ced or
  177. whatever) and will then default to 'REXX:RexxProg.rexx' if the preceeding
  178. search fails.
  179.  
  180. Limitations:
  181. ~~~~~~~~~~~~
  182.  
  183. The current setup requires a fairly strict hierarchy of directories within
  184. your development directory path.  I am working on a way to improve this at
  185. the moment.  I see it as a 'good thing' (tm) to keep development scripts in
  186. a directory of it's own anyway since this helps to keep bits together and
  187. leaves a logical point to create a distribution archive or store
  188. documentation and development notes or other ancilliary files associated
  189. with that project that may change regularly while development continues.
  190.  
  191. (Note: This limitation has been made somewhat more flexible.  You can now
  192. edit any script in any directory by select/click and can create a new
  193. project as a directory in the current path.  In my own use, this is about
  194. as far as I want to take this particular 'limitation' so if you want other
  195. capabilities in this respect, please let me know - or fix it yourself...
  196. <g>).
  197.  
  198. Feedback:
  199. ~~~~~~~~~
  200.  
  201. If you have any suggestions or ideas on this project please feel free to
  202. get in touch.  I'll implement anything that looks like a good idea to me.
  203. <grin>  Development work is ongoing as this is the environment that I
  204. currently use to write my own AREXX scripts and as and when I see a way to
  205. enhance the setup I make the required alterations.
  206.  
  207. I can be reached in the following ways:
  208.  
  209.       Usenet:    dfreeman@icecave.apana.org.au (Preferred)
  210.                  dfreeman@peg.apc.org (If the above does not work)
  211.  
  212.          IRC:    dfreeman (If you happen to see me - I'm not on all that
  213.                            often)
  214.  
  215.      FIDONet:    3:640/535  - Dave Freeman
  216.     AmigaNet:    41:450/533 - Dave Freeman
  217.  
  218.  
  219. Distribution:
  220. ~~~~~~~~~~~~~
  221.  
  222. This project is currently freely distributable but I maintain the rights to
  223. the scripts included.  If you alter the function of these scripts in any
  224. way please forward a copy of your changed script to me via one of the above
  225. methods.
  226.  
  227.